/*
 * This is a part of presence service framework API. 
 * See javadoc for more information.
 *  
 * Copyright (C) 2006 Grossmann Mark
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

package il.ac.biu.cs.grossmm.api.flow;

import il.ac.biu.cs.grossmm.api.OperationFailedException;
import il.ac.biu.cs.grossmm.api.data.NodeType;
import il.ac.biu.cs.grossmm.api.keys.KeyPattern;

/**
 * Provides methods to create and remove data publication, notification and
 * subscription points.
 * <p>
 * 
 * 
 * @author Mark Grossmann
 */
public interface ActiveDataManager {
	/**
	 * Creates new subscription point
	 * 
	 * @param <N>
	 *            type of data associated with this point
	 * @param subscriber
	 *            subscriber to recieve notifications
	 * @param pattern
	 *            java class object of the subscription point will receive
	 *            subscriptions with keys matching this pattern
	 * @param nodeInterface
	 *            the node type interface to be associated with this
	 *            subscription point. Only data nodes of this type can be
	 *            accessed via this subscription point.
	 * @return the created subscription point
	 */
	<N> SubscriptionPoint<N> createSubscriptionPoint(Subscriber<N> subscriber,
		KeyPattern pattern, NodeType<N> nodeType);

	/**
	 * Removes existing subscription point
	 * 
	 * @param <N>
	 *            type of data associated with this point
	 * @param subscriptionPoint
	 *            the subscription point to remove
	 */
	<N> void removeSubscriptionPoint(SubscriptionPoint<N> subscriptionPoint);

	/**
	 * Creates a new notification point
	 * 
	 * @param <N>
	 *            type of data associated with this notification point
	 * @param notifier
	 *            the notifier responsible for sending notifications about
	 *            changes in data defined by this notification point
	 * @param pattern
	 *            the pattern to be associated with this notification point.
	 *            only data nodes with keys matching this pattern can be
	 *            accessed via this notification point
	 * @param nodeInterface
	 *            java class object of the node type interface to be associated
	 *            with this notification point. Only data nodes of this type can
	 *            be accessed via this notification point.
	 * @param priority
	 *            the priority to be associated with this notification point
	 * @return the created notification point
	 */
	<N> NotificationPoint<N> createNotificationPoint(Notifier<N> notifier,
		KeyPattern pattern, NodeType<N> nodeType, double priority);

	/**
	 * Removes existing notification point
	 * 
	 * @param <N>
	 *            type of data associated with this point
	 * @param notification
	 *            the notification point to remove
	 */
	<N> void removeNotificationPoint(NotificationPoint<N> notificationPoint);

	/**
	 * Creates a shared publication point for given key pattern and node type.
	 * 
	 * @param <N>
	 *            node interface for this publication point
	 * @param pattern
	 *            the key pattern associated with the publication point to
	 *            create
	 * @param nodeInterface
	 *            java class object of the node type interface to be associated
	 *            with this notification point. Only data nodes of this type can
	 *            be stored on this publication point.
	 * @param persistent
	 *            if true, the data stored in this data point will be persistent
	 *            (i.e. stored on HDD or RDBMS)
	 * @param identifier
	 *            a string name which should be unique within all publication
	 *            points
	 */
	<N> PublicationPoint<N> createPublicationPoint(KeyPattern pattern,
		NodeType<N> nodeType, boolean persistent, String identifier)
		throws OperationFailedException;

	/**
	 * Get publication point by its identifier
	 * 
	 * @param <N>
	 *            node interface for this publication point
	 * @param identifier
	 *            existing publication point identifier
	 * @return publication point with the specified identifier, or null is no
	 *         such point exists
	 * @throws OperationFailedException
	 */
	<N> PublicationPoint<N> getPublicationPoint(String identifier)
		throws OperationFailedException;

	/**
	 * Removes publication point by its name
	 * 
	 * @param <N>
	 * @param identifier
	 * @throws OperationFailedException
	 */
	<N> void removePublicationPoint(String identifier)
		throws OperationFailedException;

	/**
	 * Registers a type converter
	 * @param <Nsrc> 
	 * @param <Ndst>
	 * @param converter the type converter to register
	 */
	<Nsrc, Ndst> void registerConverter(Converter<Nsrc, Ndst> converter);
}
